Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/cpp_libs/options.lha/options/README

Text File | 1993-04-13 | 5.1 KB | 158 lines

 WHAT IS THIS?
 =============
 This is "Options", a C++ library for parsing Unix-style command-line options.
 Options understands options and gnu-long-options and the parsing behavior is
 somewhat configurable. See the documentation (or the file <options.h>) for a
 complete description.

 You "declare" your options by declaring an array of strings like so:

        const char * optv[] = {
            "c:count <number>",
            "s?str   <string>",
            "x|xmode",
            NULL
        } ;

 Note the character (one of ':', '?', '|', '*', or '+') between the short
 and long name of the option. It specifies the option type:

        '|' -- indicates that the option takes NO argument;
        '?' -- indicates that the option takes an OPTIONAL argument;
        ':' -- indicates that the option takes a REQUIRED argument;
        '*' -- indicates that the option takes 0 or more arguments;
        '+' -- indicates that the option takes 1 or more arguments;

 Using the above example, optv[] now corresponds to the following:

        progname [-c <number>] [-s [<string>]] [-x]

 Using long-options, optv corresponds to the following ("-" or "+" may
 be used instead of "--" as the prefix):

        progname [--count <number>] [--str [<string>]] [--xmode]

 Now you can iterate over your options like so:

      #include <stdlib.h>
      #include <options.h>

      main(int argc, char *argv[]) {
         Options  opts(*argv, optv);
         OptArgvIter  iter(--argc, ++argv);
         const char *optarg, *str = NULL;
         int  errors = 0, xflag = 0, count = 1;

         while( char optchar = opts(iter, optarg) ) {
            switch (optchar) {
            case 's' :
               str = optarg; break;
            case 'x' :
               ++xflag; break;
            case 'c' :
               if (optarg == NULL)  ++errors;
               else  count = (int) atol(optarg);
               break;
            default :  ++errors; break;
            } //switch
         }
         ...  // process the rest of the arguments in "iter"
      }


 AUTHOR
 ======
 Brad Appleton                     Harris Corp., Computer Systems Division
   Senior Software Engineer        2101 West Cypress Creek Road,  M/S 161
     [e-mail]       Fort Lauderdale, FL  33309-1892  USA
       ...!uunet!travis!brad              Phone: [phone]


 COPY/REUSE POLICY
 =================
 Permission is hereby granted to freely copy and redistribute this
 software, provided that the author is clearly credited in all copies
 and derivations. Neither the names of the authors nor that of their
 employers may be used to endorse or promote products derived from this
 software without specific written permission.


 DISCLAIMER
 ==========
 This software is provided ``As Is'' and without any express or implied
 warranties.  Neither the authors nor any of their employers (including
 any of their subsidiaries and subdivisions) are responsible for maintaining
 or supporting this software or for any consequences resulting from the
 use of this software, no matter how awful, even if they arise from flaws
 in the software.


 CONTENTS
 ========
 See the file "MANIFEST" in the distribution for a complete list and
 description of all the files included in this release.


 REQUIREMENTS
 ============
 This software should compile on most Unix platforms with a C++ compiler
 with little or no difficulty.


 PORTING
 =======
 Options uses the AT&T C++ iostream library.  Beyond that, all the
 #include files it uses are assumed to have the contents specified by
 the ANSI-C standard and are assumed to have #ifdef __cplusplus statements
 for when they are being included by C++ files.  Options assumes the
 existence of the following system header files:

         <stdarg.h>
         <stdlib.h>
         <string.h>
         <ctype.h>
         <iostream.h>

  Other porting problems you may experience are as follows:

    - you may need to use <varargs.h> instead of <stdarg.h>

 You will need to tweak the Makefile a tad in order to make it work
 for your C++ compiler.


 BUGS
 ====
 Please send all bug reports to Brad Appleton <[e-mail]>.
 Dont forget to mention which version of Options you have and which
 operating system and C++ compiler you are using.


 ACKNOWLEDGEMENTS
 ================
 Options is a complete C++ re-write of an ANSI-C package named "getopts"
 that I wrote for the FSF that was posted on one of the "gnu" newsgroups
 (I think it was the group gnu.utils.bug) in February of 1992.  Many thanks
 to David J. MacKenzie for his input.  Options provides may more features
 than "getopts" did.  If you want the original "getopts" package (which
 has since been vastly enhanced) then send me e-mail.


 PATCHLEVEL
 ==========
 The is release 1 of Options at patchlevel 1.


 HISTORY
 =======

 07/21/92        Brad Appleton        <[e-mail]>
 -----------------------------------------------------------------------------
 First release.

 03/23/93        Brad Appleton        <[e-mail]>
 -----------------------------------------------------------------------------
 - Made some changes for compiling with g++
 - Added OptIstreamIter class